<@page title="Installing" keywords="installing, install, setup">

<@sect title="Warning!">
<p>FMPP, as a bulk file processor, may generates high amount of output files, and <@e>overwrites all files</@> with the same names as the names of output files without warning. It's a practical decision comes from the usage pattern of the tool. So be careful with where the output files go!</p>
</@sect>

<@sect title="Pre-requirements">
<ul>
  <li>Java must be installed on your machine (version 5 or later). Java is available for free, and on various platforms (Windows, OS X, "Linux", etc.), so FMPP works on many platforms. There are some variations, all is fine: OpenJDK (popular on Linux), Oracle Java SE JRE, Oracle Java SE JDK, etc.
  <li>If you want to use FMPP as an Apache Ant task, you need Apache Ant 1.5.1 or later.
</ul>
</@sect>

<@sect title="Extracting">
<p>Extract the downloaded archive file (<@c>fmpp_<@r>X</@r>.<@r>X</@r>.<@r>X</@r>.tar.gz</@c> or <@c>fmpp_<@r>X</@r>.<@r>X</@r>.<@r>X</@r>.zip</@c>) into the directory where you prefer to store FMPP. For Windows users it is typically <@c>C:\Program Files\fmpp</@> or <@c>C:\fmpp</@>, for UN*X users it is typically <@c>~/opt/fmpp</@> or <@c>/opt/fmpp</@> or <@c>/usr/lib/fmpp</@c> (where <@c>fmpp</@c> is the extracted <@c>fmpp_<@r>X</@r>.<@r>X</@r>.<@r>X</@r></@c> directory after renaming). From now on I will refer to this directory as <@c><@r>&lt;FMPP_HOME></@></@>.</p>

<p>

</@sect>

<@sect title="Setup the command-line tool" anchor="commandLineTool">

<@sect title="On Windows">
<p>The steps are:</p>
<ol>
  <li>Extract the downloaded archive file (<@c>fmpp_${pp.version}.tar.gz</@c> or <@c>fmpp_${pp.version}.zip</@c>) into <@c>C:\Program Files\fmpp</@c> (note that "Program Files" may be shown in a localized form, like "Programme"), or into <@c>C:\fmpp</@c>, or wherever you prefer to. From now on I will refer to this directory as <@c><@r>&lt;FMPP_HOME></@></@></li>
  <li>For convenience (optional), add <@c><@r>&lt;FMPP_HOME></@>/bin</@> to the <@c>PATH</@c> environment variable. (How? Google: set path windows)</li>
  <li>Check if <@c>fmpp.bat</@> isn't present in <@c>C:\Windows</@c> (or in another directory in the <@c>PATH</@c>) from an earlier installation. Delete it if it does.</li>
  <li>Check if the <@c>JAVA_HOME</@c> environment variable is set correctly (should point to your Java installation directory, not its <@c>bin</@c> subdirectory), or else that the intended version of the <@c>java</@c> executable is in the <@c>PATH</@c>. Otherwise FMPP may won't find Java.</li>
  <li>To check that everything works, open a command line window and issue: <@c>fmpp --version</@c></li>
</ol>

<p>Note: Because of the limitations of <@c>.bat</@c> files, you may get error messages like "The input line is too long". To solve this, install FMPP in a more "shallow" directory, so that the path to the FMPP related files will be shorter.</p>

</@sect>

<@sect title="On UN*X (Linux, FreeBSD, OS X, etc.)">
<p>The steps are:</p>
<ol>
  <li>Extract the downloaded archive file (<@c>fmpp_${pp.version}.tar.gz</@c> or <@c>fmpp_${pp.version}.zip</@c>) into the <@c>~/opt/fmpp</@> or <@c>/opt/fmpp</@> or <@c>/usr/lib/fmpp</@c> directory (conventions vary by distribution), or wherever you prefer to. From now on I will refer to this directory as <@c><@r>&lt;FMPP_HOME></@r></@c>.
  </li>
  <li>For convenience (optional), create a soft link somewhere in the <@c>PATH</@c>, like <@c>sudo ln -s <@r>&lt;FMPP_HOME></@r>/bin/fmpp /usr/bin/fmpp</@c>. (Alternatively, you can copy that shell script directly into <@c>/usr/bin/</@>, or into other standard directory, and it will still automatically find the <@c><@r>&lt;FMPP_HOME></@r></@c> as far as it's one of the above listed well known directories, or if you have set the <@c>FMPP_HOME</@c> environment variable yourself.)</li>
  <li>Issue <@c>which fmpp</@c> to see if it's not shadowed by an earlier installation elsewhere.</li>
  <li>Check if the intended version of the <@c>java</@c> executable is in the <@c>PATH</@c>, or else that the <@c>JAVA_HOME</@c> environment variable is set correctly (should point to your Java installation directory, not its <@c>bin</@c> subdirectory).</li>
  <li>To check that everything works, issue this in the command line: <@c>fmpp --version</@c></li>
</ol>
</@sect>

<@sect title="Notes">
<ul>
  <li>If the <@c>FMPP_HOME</@c> environment variable is set, <@c><@r>&lt;FMPP_HOME></@r>\bin\fmpp.bat</@c> and <@c><@r>&lt;FMPP_HOME></@r>\bin\fmpp</@c> will use that directory as <@c><@r>&lt;FMPP_HOME></@></@>.</li>
  <li>You can run FMPP without the provided shell scripts directly with the <@c>java</@c> command, like <@c>java -jar <@r>&lt;FMPP_HOME></@r>/lib/fmpp.jar</@c>. (You can also put all required jar-s and class directories into the <@c>CLASSPATH</@> and then issue <@c>java fmpp.tools.CommandLine</@c>.) Note though that you will lose console width detection with these approaches.</li>
  <li>You can move the jars into the <@c>lib</@c> subdirectory of Ant (if you want to use the Ant task anyway). If you do this, the command line tool need Ant be installed on a "standard" location (like <@c>C:\Program Files\ant</@c>), or <@c>ANT_HOME</@c> must be correctly set.</li>
</ul>
</@sect>
  
</@sect>


<@sect title="Setup the Ant task">

<p>If you want to use FMPP as Apache Ant task, copy the required jar files from <@c><@r>&lt;FMPP_HOME></@>/lib</@> into the <@c>lib</@> directory of your Ant installation, or ensure that the jars are in the <@c>CLASSPATH</@> environment variable. Then, whenever you need the FMPP task in a project, add this line to your <@c>build.xml</@c>:</p>

<@prg><taskdef name="fmpp" classname="fmpp.tools.AntTask"/></@prg>

<p>And then you can use the <@c>&lt;fmpp <@r>...</@r>></@> task.
</@sect>


<@sect title="Installing optional parts and custom extensions">

<p>For the command-line tool, simply drop the jar file that contains the additional classes into the <@c><@r>&lt;FMPP_HOME></@>/lib</@> directory (or, into the Apache Ant <@c>lib</@c> directory, if you only use FMPP as Ant task). For the Ant task, either ensure that the required jars are in the <@c>CLASSPATH</@c>, or drop the jars into the <@c>lib</@c> directory of your Ant installation.</p>

</@sect>

<@sect title="Updating FreeMarker" anchor="updatingFreeMarker">

<p>You can replace the included Apache FreeMarker version with a later version. <a href="${freemarkerWebsite}">Download the latest backward compatible FreeMarker release</a>, and overwrite <@c><@r>&lt;FMPP_HOME></@>/lib/freemarker.jar</@c> with the <@c>freemarker.jar</@c> of the FreeMarker release. (Of course, if you are using the FMPP Ant task, you may need to replace the <@c>freemarker.jar</@c> in the <@c>lib</@c> directory of the Ant installation too.)</p>

</@sect>

</@page>